fix: support complete agent card URL in A2ACardResolver by ehsavoie · Pull Request #837 · a2aproject/a2a-java

ehsavoie · 2026-04-29T09:59:24Z

URI.resolve() silently drops intermediate path segments when the
resolved path starts with '/', causing incorrect URLs for agents
hosted under a path prefix (e.g. /spec03). Replace with direct
concatenation and add a pass-through guard when the supplied URL
already ends with the agent card path.

Fixes #771 🦕

gemini-code-assist

Code Review

The pull request enhances A2ACardResolver to accept either a base URL or a complete agent card URL, updating the internal URL construction logic to handle these variations correctly. It also introduces several unit tests to validate URL resolution with tenants, custom paths, and authentication headers, while improving error handling in the test suite. Feedback was provided to address a potential double-slash issue when concatenating the base URL and the agent card path.

ehsavoie · 2026-04-29T13:06:59Z

/gemini review

gemini-code-assist

Code Review

This pull request updates the A2ACardResolver to support base URLs that already include the agent card path, ensuring the resolver uses such URLs verbatim. The URL construction logic was modified to handle manual concatenation when URI.resolve() is insufficient, and comprehensive unit tests were added to cover new functionality and error cases. Feedback was provided regarding a potential double-slash issue in the manual URL concatenation logic, along with a suggestion for a more robust normalization approach.

jmesnil

I'm not sure if we should make the card resolver more complex.
I see 2 use case for fetching an agent card:

use the spec's well-known endpoint that is appended to whatever the baseUrl is (it can be http://example.com, http://example.com/agents/v1/foo)
point to a specific URL that returns an agent card. This does not have to end with .well-known/.agent-card.json. This URL can be fetched from a registry for example. In that case, there is no URL resolution at all, it's used verbatim.

So the API would be:

A2AResolver(String url) (and all its variant)
AgentCard getWellKnownAgentCard() -> append `.well-known/.agent-card.json to the base URL
AgentCard getAgentCard() -> use the URL verbatim

That's be a API break change so maybe we could have just a new method:

AgentCard getAgentCard(boolean fromWellKnownLocation)
- getAgentCard() delegates to getAgentCard(true)
- the resolution of the URL is deferred until getAgentCard(boolean) is called to figure out which URL to connect to.

ehsavoie · 2026-05-04T13:45:22Z

@jmesnil I broke the API because I think it is cleaner and clearer that way

kabir · 2026-05-18T15:49:01Z

/gemini review

gemini-code-assist

Code Review

This pull request refactors the A2ACardResolver utility to use a builder pattern and introduces separate methods for retrieving well-known and configured agent cards. It also adds logging, improves URL resolution logic, and updates relevant tests and examples. Feedback was provided regarding the authHeader builder method, which could throw an UnsupportedOperationException if an immutable map is used, and a suggestion was made to normalize the Authorization header casing for consistency.

ehsavoie · 2026-05-19T10:18:00Z

/gemini review

gemini-code-assist

Code Review

This pull request refactors the A2ACardResolver to use a builder pattern and introduces distinct methods for fetching well-known versus configured agent cards. It includes URL normalization logic to handle trailing slashes and path prefixes more robustly, along with enhanced logging and updated test coverage. Feedback was provided regarding the resolveAgentCardUrl method, noting that its path-matching guard is currently hardcoded to the default path and should instead dynamically check against the specific path being resolved to avoid incorrect results when custom paths are used.

kabir

Also since I think this changes the API the prefix to the PR title should be "fix!" rather than "fix"

kabir · 2026-05-28T08:39:09Z

+     * @deprecated Use {@link #getConfiguredAgentCard()} for fetching the configured card URL, or
+     * {@link #getWellKnownAgentCard()} for the standard well-known endpoint.
     */
+    @Deprecated


Could we just not keep this method and remove the two new methods?
It seems a bit cumbersome to have the user choose between getConfiguredAgentCard() and getWellKnownAgentCard().
In my mind, if one is configured we return that, and if not we fallback to the well known one

We always have both since both are based on the builtBaseUri

URI.resolve() silently drops intermediate path segments when the resolved path starts with '/', causing incorrect URLs for agents hosted under a path prefix (e.g. /spec03). Replace with direct concatenation and add a pass-through guard when the supplied URL already ends with the agent card path. Signed-off-by: Emmanuel Hugonnet <ehugonne@redhat.com>

ehsavoie · 2026-05-28T14:05:56Z

/gemini review

gemini-code-assist

Code Review

This pull request refactors A2ACardResolver to use a builder pattern and introduces separate methods for fetching well-known and configured agent cards, updating all client usages and tests accordingly. The review feedback points out a critical breaking change from removing public constructors and a bug where configuredAgentCardUrl incorrectly defaults to the base URL instead of the well-known URL when the card path is empty. Additional suggestions include allowing authHeaders to be explicitly cleared in the builder and simplifying the resolver logic in A2A.java once the default URL bug is resolved.

gemini-code-assist · 2026-05-28T14:08:05Z

+    private A2ACardResolver(A2AHttpClient httpClient, String baseUrl, @Nullable String tenant, @Nullable String agentCardPath, @Nullable Map<String, String> authHeaders) throws A2AClientError {
+        checkNotNullParam("httpClient", httpClient);
+        checkNotNullParam("baseUrl", baseUrl);
+        this.httpClient = httpClient;
+        try {
+            URI builtBaseUri = new URI(org.a2aproject.sdk.util.Utils.buildBaseUrl(new AgentInterface("JSONRPC", baseUrl, ""), tenant));
+            this.wellKnownUrl = resolveAgentCardUrl(builtBaseUri, DEFAULT_AGENT_CARD_PATH).toString();
+            this.configuredAgentCardUrl = (agentCardPath == null || agentCardPath.isBlank())
+                    ? builtBaseUri.toString()
+                    : resolveAgentCardUrl(builtBaseUri, agentCardPath).toString();
+
+            LOGGER.debug("Initialized A2ACardResolver with wellKnownUrl={}, configuredAgentCardUrl={}", wellKnownUrl, configuredAgentCardUrl);
+        } catch (URISyntaxException e) {
+            throw new A2AClientError("Invalid agent URL", e);
+        }
+        this.authHeaders = authHeaders;
    }


Removing all public constructors from A2ACardResolver is a breaking change for any external clients/consumers of this SDK. To maintain backward compatibility, we should keep the most common constructors and mark them as @Deprecated instead of removing them entirely.

Additionally, configuredAgentCardUrl should default to wellKnownUrl when agentCardPath is null or blank. Currently, it defaults to builtBaseUri.toString(), which points to the base URL of the agent (e.g., http://localhost:9999) rather than the agent card URL (e.g., http://localhost:9999/.well-known/agent-card.json). This breaks the deprecated getAgentCard() method and any direct usage of getConfiguredAgentCard() where agentCardPath is not explicitly set.

@Deprecated public A2ACardResolver(String baseUrl) throws A2AClientError { this(A2AHttpClientFactory.create(), baseUrl, null, null, null); } @Deprecated public A2ACardResolver(String baseUrl, @Nullable String tenant) throws A2AClientError { this(A2AHttpClientFactory.create(), baseUrl, tenant, null, null); } private A2ACardResolver(A2AHttpClient httpClient, String baseUrl, @Nullable String tenant, @Nullable String agentCardPath, @Nullable Map<String, String> authHeaders) throws A2AClientError { checkNotNullParam("httpClient", httpClient); checkNotNullParam("baseUrl", baseUrl); this.httpClient = httpClient; try { URI builtBaseUri = new URI(org.a2aproject.sdk.util.Utils.buildBaseUrl(new AgentInterface("JSONRPC", baseUrl, ""), tenant)); this.wellKnownUrl = resolveAgentCardUrl(builtBaseUri, DEFAULT_AGENT_CARD_PATH).toString(); this.configuredAgentCardUrl = (agentCardPath == null || agentCardPath.isBlank()) ? this.wellKnownUrl : resolveAgentCardUrl(builtBaseUri, agentCardPath).toString(); LOGGER.debug("Initialized A2ACardResolver with wellKnownUrl={}, configuredAgentCardUrl={}", wellKnownUrl, configuredAgentCardUrl); } catch (URISyntaxException e) { throw new A2AClientError("Invalid agent URL", e); } this.authHeaders = authHeaders; }

I disagree, we could have the final url passed as the base url without any agentPath

gemini-code-assist · 2026-05-28T14:08:05Z

+        public Builder authHeaders(@Nullable Map<String, String> authHeaders) {
+            if (authHeaders != null) {
+                this.authHeaders = new HashMap<>(authHeaders);
+            }
+            return this;
+        }


If authHeaders is null, the builder currently leaves this.authHeaders unmodified. To allow clearing headers or setting them to null explicitly, we should assign null when the parameter is null.

public Builder authHeaders(@Nullable Map<String, String> authHeaders) { this.authHeaders = authHeaders != null ? new HashMap<>(authHeaders) : null; return this; }

We don't want null headers

gemini-code-assist · 2026-05-28T14:08:05Z

+        return (relativeCardPath == null || relativeCardPath.isBlank())
+                ? resolver.getWellKnownAgentCard()
+                : resolver.getConfiguredAgentCard();


With the fix applied to A2ACardResolver where configuredAgentCardUrl correctly defaults to wellKnownUrl when agentCardPath is null or blank, we can simplify this logic and remove the ternary operator check.

return resolver.getConfiguredAgentCard();

ehsavoie requested a review from jmesnil April 29, 2026 09:59

gemini-code-assist Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread http-client/src/main/java/org/a2aproject/sdk/client/http/A2ACardResolver.java Outdated

ehsavoie force-pushed the issue_771 branch from 5ce27bb to b2a8201 Compare April 29, 2026 13:06

gemini-code-assist Bot reviewed Apr 29, 2026

View reviewed changes

Comment thread http-client/src/main/java/org/a2aproject/sdk/client/http/A2ACardResolver.java Outdated

jmesnil reviewed Apr 30, 2026

View reviewed changes

ehsavoie force-pushed the issue_771 branch from b2a8201 to 8b7192d Compare May 4, 2026 13:43

ehsavoie requested a review from jmesnil May 4, 2026 13:45

ehsavoie force-pushed the issue_771 branch from 8b7192d to 089764d Compare May 5, 2026 09:03

ehsavoie requested review from kabir May 5, 2026 16:01

ehsavoie force-pushed the issue_771 branch from 089764d to a406047 Compare May 18, 2026 15:34

gemini-code-assist Bot reviewed May 18, 2026

View reviewed changes

Comment thread http-client/src/main/java/org/a2aproject/sdk/client/http/A2ACardResolver.java

ehsavoie force-pushed the issue_771 branch from a406047 to 247cf08 Compare May 19, 2026 10:17

gemini-code-assist Bot reviewed May 19, 2026

View reviewed changes

Comment thread http-client/src/main/java/org/a2aproject/sdk/client/http/A2ACardResolver.java Outdated

ehsavoie force-pushed the issue_771 branch 2 times, most recently from e915a3b to 103105c Compare May 19, 2026 15:03

ehsavoie force-pushed the issue_771 branch from 103105c to f51654b Compare May 28, 2026 08:04

kabir reviewed May 28, 2026

View reviewed changes

ehsavoie force-pushed the issue_771 branch from f51654b to 2e3294b Compare May 28, 2026 14:05

gemini-code-assist Bot reviewed May 28, 2026

View reviewed changes

Conversation

ehsavoie commented Apr 29, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

ehsavoie commented Apr 29, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

jmesnil left a comment

Choose a reason for hiding this comment

Uh oh!

ehsavoie commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kabir commented May 18, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

ehsavoie commented May 19, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

kabir left a comment

Choose a reason for hiding this comment

Uh oh!

kabir May 28, 2026

Choose a reason for hiding this comment

Uh oh!

ehsavoie May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ehsavoie commented May 28, 2026

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

ehsavoie May 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

ehsavoie May 28, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 28, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ehsavoie commented May 4, 2026 •

edited

Loading

ehsavoie May 28, 2026 •

edited

Loading